大家好，又见面了。

在JAVA做前后端分离的项目开发的时候，服务端需要提供接口文档供周边人员做接口的对接指导。越来越多的项目都在尝试使用一些基于代码自动生成接口文档的工具来替代由开发人员手动编写接口文档，而Swagger作为一款优秀的在线接口文档生成工具，以其功能强大、集成方便而得到了广泛的使用。

在项目中有一种非常常见的场景，就是接口的请求或者响应参数中会有一些字段的取值会限定为固定的几个可选值之一，而在代码中这些可选值往往会通过定义枚举类的方式来承载，比如：

根据操作类型，过滤对应类型的用户操作日志列表 如: http://127.0.0.1:8088/test/queryOperateLogs?operateType=2

这里的请求参数operateType传入的值需要在后端约定的取值范围内，这个取值范围的定义如下：

这里就需要我们在接口文档里面将此接口中operateType的可选值以及每个可选值对应的含义信息都说明清楚，这样调用方在使用的时候才知道应该传入什么值。

我们基于Swagger提供的基础注解能力来实现时，比较常见的会看到如下两种写法：

接口URL中携带的请求入参信息，通过@ApiImplicitParam注解来告诉调用方此接口允许接收的合法operateType的取值范围以及各个取值的含义。

比如下面这种场景：

 这样，在swagger界面上就可以显示出字段的取值说明信息。

其实还有一种写法，即在代码的入参前面添加@ApiParam注解的方式来实现。比如：

这样也能达到相同的效果。

对于需要使用json体进行传输的请求或者响应消息体Model中，可以使用@ApiModelProperty添加含义说明。

同样，在Swagger界面就可以清楚的知道每个字段的具体含义与取值说明。

​但是上面的两个写法，都存在着同一个问题，就是如果枚举类中的值内容含义有变更，比如OperateType枚举类中新增了一个BATCH_DELETE(5, "批量删除"), 则必须手动去修改所有涉及的接口上的Swagger描述信息。如果有大量场景都涉及此字段，则要改动的地方就非常多，且极易漏掉（因为不好通过代码关联关系直接搜索到）。这样对于开发人员维护起来的成本就会增加，久而久之会导致接口文档的内容与实际代码处理情况不相匹配。

编辑切换为居中

那么，有没有什么简单的方式，可以让接口文档自动根据对应枚举类的内容变更而动态变更呢？

Swagger没有提供原生的此方面能力支持，但是我们可以通过一些简单的方式对Swagger的能力进行扩展，让Swagger支持我们的这种诉求。一起来看下如何实现吧。

既然想要改变生成的Swagger文档中指定字段的描述内容，那么首先就应该是要搞清楚Swagger中现在的内容生成逻辑是如何处理的。我们以@ApiParam为例进行分析。因为@ApiParam中指定的内容会被显示到Swagger界面上，那么在Swagger的框架中，一定有个地方会尝试去获取此注解中指定的相关字段值，然后将注解的内容转为界面上的文档内容。所以想要定制，首先必须要了解当前是如何处理的。

翻看Swagger的源码，发现在ApiParamParameterBuilder类中进行此部分逻辑的处理，处理逻辑如下：

看了下此类是ParameterBuilderPlugin接口的一个实现类，Swagger框架在遍历并逐个生成parameter说明信息的时候会被调用此实现类的逻辑来执行。

到这里其实问题就已经很明显了，我们可以自定义一个处理类并实现ParameterBuilderPlugin接口，然后将我们的诉求在自定义的处理类中进行实现，这样不就可以实现我们的诉求了吗？

相同的策略，我们可以找到处理@ApiImplicitParam、@ApiModelProperty对应的接口类。

​根据上面的分析，我们只需要提供个自定义实现类，然后分别实现这几个接口就可以搞定我们的诉求了。那应该如何进行封装，将其作为一个通用能力供所有场景使用呢，下面详细讨论下。

前面已经找到了一种思路将我们的定制逻辑注入到Swagger的文档生成框架中进行调用，那么下一步我们就得确认一种相对简单的策略，告诉框架哪个字段需要使用枚举来自动生成取值说明，以及使用哪个枚举类来生成。

这里我们使用自定义注解的方式来实现。Swagger为不同的场景分别提供了@APIParam、@ApiImplicitParam、@ApiModelProperty等不同的注解，我们可以简化下，提供一个统一的自定义注解即可。

比如：